---
title: Retroboot installation manual
...

This section relates to installing Retroboot on supported targets.
NOTE: This only applies to the Git repository. Efforts are made to keep these
instructions compatible with release archives, BUT: if you are using a release
archive instead of the Git repository, please instead refer to the
documentation included in that release archive! This applies to *all*
documentation on Retroboot's website, for the most part, but *especially*
the install guides! Retroboot is a very young project and, as such, it is
constantly evolving.

NOTE: if running `flashrom -p internal` for software based flashing, and you
get an error related to `/dev/mem` access, you should reboot with
`iomem=relaxed` kernel parameter before running flashrom, or use a kernel that
has `CONFIG_STRICT_DEVMEM` not enabled.

General information
-------------------

-   [What systems are compatible with Retroboot?](../hardware/)
-   [Information about Retroboot ROM images](#rom)
-   [Information about ich9utils software and ICH9 Flash Descriptor (X200/T400/etc)](ich9utils.md)
-   [CPU microcode on Libreboot-compatible targets](#microcode)

Flashing via software methods, on system:
-----------------------------------------

-   [ThinkPad X200/X200S/X200T if already running Retroboot/Libreboot](#gm45)
-   [ThinkPad X220/T420/T420S if already running Retroboot with Neutered ME and ifdtool-unlocked regions](#x220t420)
-   [ThinkPad X230/X230T if already running Retroboot with Neutered ME and ifdtool-unlocked regions](#x230)
-   [ThinkPad X60/X60S/X60T/T60 with Mobility Radeon X1400 (if already running Retroboot/coreboot)](#i945)
-   [ThinkPad X60/X60S/X60T/T60 with Mobility Radeon X1400 (if running Lenovo BIOS)](#flashrom_lenovobios)

Setting up programmers, for external SPI flashing 
-------------------------------------------------

-   [Raspberry Pi Setup](rpi_setup.md) (ISP - In System Programming)

Flashing via hardware methods, on system:
-----------------------------------------

-   [ThinkPad X60/X60S](x60_unbrick.md)
-   [ThinkPad X60 Tablet](x60tablet_unbrick.md)
-   [ThinkPad T60 with Mobility Radeon X1400 PCI ID 1002:7145](t60_unbrick.md)
-   [ThinkPad X200 (NOT X200S/X200Tablet)](x200_external.md)
-   [ThinkPad X200S / X200 Tablet](#x200st)
-   [ThinkPad X220](x220_external.md)
-   [ThinkPad T420/T420S](t420_external.md)
-   [ThinkPad X230/X230T](x230_external.md)

Installing Retroboot onto ThinkPad X200S or X200 Tablet {#x200st}
=======================================================

Flash the same ROM image for X200 on your X200S or X200 Tablet. They are the
same boards.

These laptops use WSON8 form factory for the NOR flash. It must be de-soldered,
and replaced with a SO8/SOIC8 NOR flash.

X200S/X200Tablet not yet fully documented on Retroboot for external flash, but
Leah Rowe has videos on her YouTube channel showing how to have Libreboot on
these. First, watch this video:

<https://www.youtube.com/watch?v=tguch_iPBZQ>

Then watch this video:

<https://www.youtube.com/watch?v=MxMKJsg5IEU>

Use `youtube-dl` to download these video, if you wish to avoid non-free
JavaScript on `youtube.com`. The Retroboot project is currently setting up a
video hosting site, which will run `GNU MediaGoblin`. However, this website is
not yet available to the public.

The plan is to, over time, host all Retroboot related videos there. A separate
virtual host is also being configured an that server, for Libreboot videos linked
on `libreboot.org`.

When you have installed Retroboot on your X200S or X200 Tablet, using these
instructions, internal flashing is possible (unless you flash a ROM with Intel
Flash Descriptor that sets flash regions read-only, in which case external
flashing is needed again but at that point, a regular SOIC8 test clip can be
used rather than having to solder anything).

*Most* people who flash X200S or X200 Tablet solder 30awg kynar wires directly
to the original WSON8, flash it and then de-solder them, and then boot up.
This is **NOT** recommended by the Retroboot project and can in fact ruin your
machine. The reason is simple: the WSON8 is a QFN type IC, and is therefore
not designed to have modwires on it. You run the risk of causing discontinuity
with the QFN/pads and where they lead to on the mainboard, and it means that
you are mixing *old* solder with *new* solder. Mixing solder chemistries is
never a good idea and can lead to cold joints.

Therefore, the Retroboot project recommends that you do it *properly*, using
the instructions in the videos linked above. You will remove the original WSON
using a hot air jet, then install the new SOIC8 using regular knife tip.

Use lots of flux! Use quality 60/40 *leaded* solder (none of that Rohs rubbish).

CPU microcode on Libreboot-compatible targets {#microcode}
=============================================

Targets from Libreboot (such as X200/T400) contain CPU microcode updates
when built using the Retroboot build system. To remove these, use cbfstool e.g.:

    cbfstool x200.retroboot.rom remove -n cpu_microcode_blob.bin

Then re-flash. When you do this, and the ROM has `libgfxinit` in the file name
(rather than `vgarom`), it will be a ROM containing only 100% Free Software,
like Libreboot.

Unlike Libreboot, Retroboot does not prohibit binary blobs in its build system.
The CPU microcode updates are useful, because they fix bugs in the CPU. For
example, power/thermal management is greatly improved on i945 laptops (X60/T60)
and virtualization is enabled on GM45 laptops (X200/T400) not to mention,
general system stability is greatly increased.

This has other benefits. For instance, Opteron 6300 CPUs are now fully
stable on D16 when flashed with a Retroboot ROM, as opposed to Libreboot.

The only binary blobs added, in Retroboot, to systems that come from Libreboot,
are:

* CPU microcode updates
* Vendor-supplied Video BIOS option ROM (on separate ROM images with `vgarom` in
  the filename. ROMs with `libgfxinit` in the file name use native video
  initialization from coreboot, exactly like Libreboot does)

Information about Retroboot ROM images {#rom}
======================================

When ROM images are provided, by the Retroboot build system, they appear under
the `bin/` directory.

[How to compile Retroboot ROM images](../git/)

You do not have to build ROM images from the source code. In addition to that,
you can also download one of the releases on the
[download page](../../download.md) where pre-compiled ROM images are available.
These ROM images are built using the exact same steps as defined in the link
above.

If you wish to help with Retroboot development (for instance, adding a board
to Retroboot that you have, which has coreboot support, and maintaining support
for it in Retroboot), you should first familiarize yourself with the Retroboot
build system. The entire build system is documented in the
[Retroboot maintenance manual](../maintain/)

General rules about ROM file names:

* `vesafb` means that coreboot starts with a high resolution VESA frame buffer
   (useful with `Tianocore` payload or `libgfxinit` especially when using
   SeaBIOS with SeaVGABIOS option ROM). When using `libgfxinit`, this is the
   most compatible option if you wish to use GNU+Linux or BSD operating 
   systems on Retroboot.
* `txtmode` means that coreboot starts in legacy VGA text mode (useful for
   legacy OS and text mode applications like memtest86+).
   This configuration is only recommended in combination with the Video BIOS
   option ROM (`vgarom` config mentioned below) but can be used with `libgfxinit`
   if you wish to run memtest86+ and FreeDOS will work (but only if you run
   text mode DOS programs)
* `vgarom` means that a Video BIOS option ROM will be used, supplied by the
   manufacturer of the target video chipset. In this configuration, `libgfxinit`
   in coreboot is disabled. The VBIOS option ROM is usually non-free.
   This is the most compatible option (recommended with SeaBIOS payload in
   `txtmode` configuration, or Tianocore with `vesafb` configuration); it has
   full INT10H and mode switching support, so even legacy DOS games will work,
   and it will enable the use of legacy operating systems (e.g. old Windows
   versions)
* `libgfxinit` means that native video initialization is used in coreboot. On
   many targets nowadays, coreboot has native video support and creates a
   frame buffer. The SeaVGABIOS option ROM (part of SeaBIOS) can use this, to
   emulate a Video BIOS (but lacks proper INT10H and video mode switching)

Beyond this, the file name of your ROM will contain the name of the machine
and the default coreboot payload (GRUB, SeaBIOS, Tianocore etc) in use.

[Read the Retroboot maintenance manual](../maintain/)

ThinkPad X200/X200S/X200T if already running Retroboot/Libreboot {#gm45}
============================================================

For X200/X200S/X200T the ROM is the same. The only difference is which ROM you
select based on the size of your boot flash (4MiB and 8MiB are most common, or
16MiB is typical if you are replacing the flash because that's the maximum
size supported on this machine).

Just use `flashrom -p internal` on a ROM supplied by the Retroboot project, or
a ROM that you built using the Retroboot build system.

Use the `-w` argument. You can also specify a custom MAC address in the GbE
region, by overwriting the default descriptor+GbE region using `ich9gen`
and `dd`.

For instructions on changing your MAC address and on the ICH9 descriptors in
general, refer to [the ich9utils page](ich9utils.md).

Example:

    flashrom -p internal -w x200.retroboot.rom

NOTE: This won't work if you flashed with an Intel Flash Descriptor that set
the regions read-only in your boot flash.

X60/X60S/X60T/T60: How to update or install retroboot (if you are already running retroboot or coreboot) {#i945}
=================================================================================================

Just use `flashrom -p internal` when flashing T60 if you already have
a Retroboot/Libreboot/Coreboot ROM with the upper 64KiB bootblock flashed
(either externally, or as a result of using the Libreboot 20160907 install
scripts for *first flash* and *second flash* (see below on this page).

Example:

    flashrom -p internal -w t60.retroboot.rom

If flashrom complains about multiple chips detected, just do what it says
and use the `-c` option to pick a chip. If it fails, pick another one.

You can find flashrom under the `flashrom/` directory in the Retroboot source
code release archives. Build it (from source) using the
[Retroboot build instructions page](../git/).

Updating/changing the X220/T420/T420S ROM if Retroboot already flashed {#x220t420}
=========================================================================

This assumes that you unlocked the regions using ifdtool, and ran me\_cleaner,
when installing Retroboot the first time. Retroboot currently does not provide
pre-compiled utilities, but you can download the source code archive of
Retroboot from the [download page](../../download.md) and build these utilities
using the instructions at [Retroboot build instructions page](../git/).

For X220 you will want to use a layout file in flashrom and only flash the
BIOS region, which is the upper 3MiB region on the default descriptor
configuration (unless you modified it to change region sizes and or move them).

For flashing the BIOS region, a custom flash layout file is included at:

    resources/coreboot/x220/flash.layout

Retroboot includes 8MiB ROM images for X220, but only the upper 3MiB of it
should be flashed, to the upper 3MiB of the flash chip. The low 5MiB of the
ROM is all `0xFF` which you should not flash; the lower 5MiB on the actual
chip contains your Intel Flash Descriptor, GbE and Intel ME regions and it's
very important that these do not get overwritten.

Assuming that you compiled `flashrom` (from Retroboot build system), you can
use the followang command to flash your ROM:

    sudo ./flashrom/flashrom -l resources/coreboot/x220/flash.layout -i coreboot -w retroboot.rom -p internal

NOTE: X220, T420 and T420S all have the same default region layout, so even
though the above specifies a flash layout for X220, the actual flash layout
included for T420/T420S are exactly the same in Retroboot. However, please
make sure that you are flashing the correct ROM image!

In the above example, `retroboot.rom` is your 8MiB ROM image. The `-i coreboot`
option specifies that only the coreboot part should be flashed, and the `-l`
argument specifying the flash layout defines that `coreboot` region as the upper
3MiB of the flash.

If your machine currently has Lenovo BIOS, OR has the default unmodified 5MiB
descriptor+gbe+me in the 8MiB flash chip then you will need to re-flash
externally using this guide:

[How to flash ThinkPad X220 externally](x220_external.md)

The linked guide instructs you 

That's only if you want to also flash the descriptor, ME and/or GbE region.
If coreboot/retroboot is already running, you can re-flash internally if
using a layout file specifying to flash only the upper 3MiB BIOS region *but*
in that situation if ME is not neutered and/or ME/descriptor region is set
read-only you must pass the following parameter as an argument in flashrom:
`--noverify-all`

However you decided to flash, flashrom will say `VERIFIED` if it was a
successful flash. After you flash, and it says VERIFIED, turn off the system,
wait a few seconds and then boot up again. If it didn't say VERIFIED, unless
othewise stated by this documentation, you should NOT turn off your system and
seek immediate help, for it may brick if you turn it off, so it may need to be
fixed. (unless flashrom didn't actually do anything because you typo'd the
command or something, like specifying a non-existing ROM on your file system)

Updating/changing the X230/X230T ROM if Retroboot already flashed {#x230}
=========================================================================

Retroboot provides separate ROM images for X230 and X230 Tablet. The instructions
are the same for both, with the only difference being which ROM you use.

NOTE: Retroboot includes ROMs with `4mb` in the file name, but these are for
external flashing, for flashing just SPI2 (the 4MiB chip). If you're doing
internal flashing (flashrom on OS running on the X230), use the `7mb` ROM. The
ROM says `7mb` in the file name, but the actual file size is 12MiB. This is
because the ROM is compiled for the 12MiB of boot flash on your X230, but with
CBFS size set to 7MiB. You will flash only the upper 7MiB of that ROM, to the
upper 7MiB of the 12MiB boot flash on your X230.

Your X230 has two flash chips: 8MiB for the lower part and 4MiB for the upper
part. Combined, this creates 12MiB of flash and this is what flashrom sees
when using `-p internal`.

This guide that you unlocked the regions using ifdtool, and ran me\_cleaner,
when installing Retroboot the first time. Retroboot currently does not provide
pre-compiled utilities, but you can download the source code archive of
Retroboot from the [download page](../../download.md) and build these utilities
using the instructions at [Retroboot build instructions page](../git/).

For X230/X230T you will want to use a layout file in flashrom and only flash the
BIOS region, which is the upper 7MiB region on the default descriptor
configuration (unless you modified it to change region sizes and or move them);
Retroboot provides the option to flash a 4MiB ROM (CBFS size 4MiB) with 3MiB
lower section of the BIOS region unused, or a full 7MiB ROM (CBFS size 7MiB)
with all of the BIOS region available to you in `cbfstool`.

The 4MiB ROM files are provided for external flashing, for flashing Retroboot
the first time, to make things a little bit simpler (just dump the whole
8MiB NOR flash, run it through `me_cleaner` and `ifdtool --unlock`, flash it
back, and then flash the 4MiB ROM to the 4MiB NOR flash).

The 7MiB ROM files are provided for internal flashing, after you flashed the
first time using the 4MiB ROM externally. You *can* flash the 7MiB file externally
but you have to split the lower 3MiB of the upper of the ROM image, and flash it (using
a layout file) to the upper 3MiB of the 8MiB NOR flash. Then you flash the upper
4MiB of that 7MiB ROM, to the 4MiB NOR flash. It's much simpler to just flash
the 4MiB ROM to the 4MiB NOR flash, then boot and OS and run
`flashrom -p internal`, with layout file, to flash the 7MiB file since the two
flash chips are seen as one big 12MiB "chip" in your operating system.

Seriously. Just use the full 12MiB images marked `7mb` and use the included
layout file. Instructions are below.

For X230 if flashing a 4MiB ROM (4MiB CBFS size), a custom flash layout file
is included here in the Git repository / archive, for internal flashing:

    resources/coreboot/x230_4mb/flash.layout

NOTE: you will need to pad the ROM if you wish to flash the 4MiB one. Just
flash the 7MiB one please (ROM is actually 12MiB, with first 5MiB being
padding).

For X230 if flashing a 7MiB ROM (7MiB CBFS size), a custom flash layout file
is included here in the Git repository / archive, for internal flashing:

    resources/coreboot/x230_7mb/flash.layout

These layout files, when used, specify that `flashrom` must only flash a certain
region. When using `flashrom -p internal` running on e.g. GNU+Linux, the 8MiB
and 4MiB NOR flash (on the X230 mainboard) are detected as a single, continuous
12MiB of flash, with the 8MiB flash being the lower section and 4MiB NOR flash
being in the upper section of what it sees.

Flash the ROM with `7mb` in the file name, and use the layout file included
in Retroboot to flash just the upper 7MiB of that ROM to the upper 7MiB of the
12MiB boot flash:

    sudo ./flashrom/flashrom -l resources/coreboot/x230_7mb/flash.layout -i coreboot -w retroboot.rom -p internal

The `-l` parameter in flashrom specifies a layout file. In that layout file is
specified an arbitrary set of regions. These regions can be within any boundaries
you like.

The 7MiB layout file (for ROMs with `7mb` in the file name) looks like this,
inside:

    00000000:004fffff intelstuff
    00500000:00bfffff coreboot

These are boundaries in bytes, specified in hexademical.

The `-i` parameter in flashrom specifies which region (as per the layout file)
should be flashed. NOTE: *region*, in this context, refers to flashrom layout
file structure, *not* regions as defined in the Intel Flash Descriptor.
So, `-i coreboot` specifies that only those boundaries in that ROM are to be
flashed within those boundaries of the NOR flash.

BE SURE to flash ONLY the `coreboot` region, where the contents of the Retroboot
ROM is what ends up being flashed there. If you mess this up, you could brick
your machine (make it unbootable). The lower 5MiB of your boot flash is the
Intel Flash Descriptor, Gbe and ME regions which should NOT be overwritten!

The above flashrom command for X230 will flash *only* the BIOS region.
The file `newretrobootrom.rom` could be a new Retroboot ROM, if you're updating
to a new version, or it could be that you are switching to a different ROM
configuration on the same version of retroboot. So long as its a coreboot image
with flash size set to 12MiB, CBFS size set to 4MiB or lower and the 4MiB
coreboot part spliced out after coreboot was built (e.g. using dd the way
the Retroboot build system does it when building ROMs. See ROM building scripts
under `resources/scripts/build/roms/` for how Retroboot does it: it builds
12MiB coreboot ROMs but everything below the upper 4MiB is 0xFF and the upper
4MiB is the coreboot ROM with CBFS size to 4MiB size, on Retroboot ROMs).

If your X230 currently has Lenovo BIOS, OR has the default unmodified 8MiB
descriptor+gbe+me in SPI1 (8MiB flash chip) you will need to re-flash
externally using this guide:

[How to flash ThinkPad X230 externally](x230_external.md)

However you decided to flash, flashrom will say `VERIFIED` if it was a
successful flash. After you flash, and it says VERIFIED, turn off the system,
wait a few seconds and then boot up again. If it didn't say VERIFIED, unless
othewise stated by this documentation, you should NOT turn off your system and
seek immediate help, for it may brick if you turn it off, so it may need to be
fixed. (unless flashrom didn't actually do anything because you typo'd the
command or something, like specifying a non-existing ROM on your file system)

ThinkPad X60/X60S/X60T/T60: Initial installation guide (if running the proprietary firmware) {#flashrom_lenovobios}
==================================================================================

For now, no integration exists in Retroboot for the first and second flash
(you need to flash twice, when flashing from LenovoBIOS to Retroboot). Go
and download the Libreboot 20160907 util release archive from
<https://libreboot.org/> and follow the instructions on the Libreboot website:

<https://libreboot.org/docs/install/#flashrom_lenovobios>

NOTE: The libreboot website doesn't tell you to back up your Lenovo BIOS, but
you *should*. Do it using this flashrom command:

    sudo flashrom -p internal -r factory.bin

A 2MiB file named `factory.bin` will have been created. If flashrom complained
about multiple flash chips detected, just do what it says and pick one using
the `-c` option.

Libreboot supports T60/X60 that has Intel GPU, whereas Retroboot supports T60
that has ATI GPU.

However, the procedure for flashing Retroboot on your T60 when you have ATI
GPU and you're running Lenovo BIOS, is exactly the same as when you have an
Intel T60 and flashing Libreboot from Lenovo BIOS.

Imagine that you're flashing Libreboot on a T60 that has Intel GPU, and follow
the instructions on that libreboot page, *but* use the T60 ROM that you compiled
in the Retroboot build system. That T60 ROM has an ATOMBIOS VGA option ROM
for the ATI Mobility Radeon X1400 GPU, and uses the SeaBIOS payload.
